package libnetdb.dm.assoc.util;

/**
 * This class provides a simple way to transfer the setting of
 * stage or progress to the delegated subtasks.
 *
 * The following is an illustrative usage of this class.
 * <pre>
 *    public class SampleTask extends ControllableTask{
 *        public void runImpl() throws Exception{
 *            new SubtaskInit(controllee);
 *            new SubtaskRun(controllee);
 *            new SubtaskFinish(controllee);
 *        }
 *    }
 * </pre>
 *
 * @author Cheng-Ru Lin and Ashley Tsai
 * @version 1.0 2002/8
 */

public class Controllee {

    private ControllableTask task;

    /**
     * Constructs a new Controllee with task as the controlled task.
     * @param task the controlled task.
     */
    Controllee(ControllableTask task) {
        this.task = task;
    }

    /**
     * Sets the current stage of the controlled task.
     * @param stage the current stage
     */
    public void setStage(String stage){
        task.setStage(stage);
    }

    /**
     * Sets the current progress of the whole task. The progress
     * is a <code>float</code> number in the range of [0,1]
     * indicating the completeness of the task.
     *
     * @param progress the progress of the task
     */
    public void setProgress(float progress){
        task.setProgress(progress);
    }

    /**
     * Post a message to all the progress listeners.
     *
     * @param message a string to be posted
     */
    public void postMessage(String message){
        task.postMessage(message);
    }

    /**
     * Sets the progress of the current stage. The progress is a
     * <code>float</code> number in the range of [0,1] indicating
     * the completeness of the stage.
     *
     * @param progress The working progress just now.
     */
    public void setStageProgress(float progress){
        task.setStageProgress(progress);
    }

    /**
     * Processes the commands given at the <code>ControllableTask
     * </code>. If the task is canceled, a UserCancelException will
     * be thrown, if paused, this function call will be blocked util
     * the task has been resumed.
     *
     * @throws UserCancelException if <code>cancel()</code> has been
     * called
     * @throws InterruptedException if another thread has interrupted
     * the current thread. The interrupted status of the current thread
     * is cleared when this exception is thrown.
     */
    public void processCommands()
            throws UserCancelException, InterruptedException{
        task.processCommands();
    }
}